home *** CD-ROM | disk | FTP | other *** search
/ Shareware Grab Bag / Shareware Grab Bag.iso / 087 / tcomm.arc / LITECOMM.DOC next >
Encoding:
Text File  |  1987-07-07  |  50.3 KB  |  2,641 lines

  1.  LiteComm Toolbox for Datalight and Turbo C
  2.  
  3.  
  4.  
  5.                                   INTRODUCTION
  6.  
  7.         The LiteComm Toolbox(tm) is a set of powerful routines designed 
  8.         to provide easy access to the full capabilities of the PC's 
  9.         asynchronous communications ports. In its initial release, the 
  10.         LiteComm ToolBox supports fully interrupt-driven and buffered 
  11.         communications support on both COM1 and COM2 simultaneously. 
  12.         Version 1.1, supplied here, supports COM3 and COM4 as well. Now 
  13.         you can quickly incorporate sophisticated communications support 
  14.         in your applications without having in-depth knowledge of how the 
  15.         hardware functions.
  16.  
  17.         The ToolBox was developed as the result of a need to provide just 
  18.         this type of support in CAM applications which were developed for 
  19.         a client. Both version of the LiteComm are heavily integrated 
  20.         with their respective host compilers.
  21.  
  22.  
  23.  
  24.  
  25.  
  26.  
  27.  
  28.  
  29.  
  30.  
  31.  
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.                 Copyright (c) 1987 Information Technology, Ltd.
  62.  
  63.  
  64.  
  65.  
  66.  
  67.                   LiteComm Toolbox for Datalight and Turbo C
  68.  
  69.  
  70.  
  71.                               THE SHAREWARE CONCEPT
  72.  
  73.         Shareware is a "try before you buy" means of software 
  74.         distribution. If you find a shareware product useful, pay the 
  75.         registration fee, and let the authors know that you support their 
  76.         efforts.
  77.  
  78.         The LiteComm ToolBox, small model library only, is distributed as 
  79.         a shareware product. To receive all model libraries and/or the 
  80.         source code for the product, register your copy today. See the 
  81.         registration form at the end of the documentation.
  82.  
  83.         The LiteComm ToolBox is not public-domain software. Information 
  84.         Technology, Ltd. grants to individuals the right to use the 
  85.         LiteComm ToolBox as a part of other products they may develop. 
  86.         Commercial use by corporations or distribution of the ToolBox for 
  87.         profit is prohibited, except with the written consent of 
  88.         Information Technology, Ltd., and may subject violators to civil 
  89.         penalties. Further, neither the LiteComm ToolBox nor its 
  90.         documentation may be distributed in any modified form.
  91.  
  92.  
  93.                                     WARRANTY
  94.  
  95.         The LiteComm ToolBox is distributed as-is and without warranty, 
  96.         including, but not limited to, the implied warranties of 
  97.         merchantability and fitness for a particular purpose.
  98.  
  99.         The user(s) of the LiteComm ToolBox agree to hold the author and 
  100.         distributors of this product harmless for any damages, either 
  101.         direct or consequential, which arise from the use of this 
  102.         product.
  103.  
  104.         DATALIGHT is a registered trademark of Datalight, Inc.
  105.         Turbo C is a trademark of Borland International, Inc.
  106.  
  107.  
  108.  
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.                 Copyright (c) 1987 Information Technology, Ltd.
  128.  
  129.  
  130.  
  131.  
  132.  
  133.                   LiteComm Toolbox for Datalight and Turbo C
  134.  
  135.  
  136.                               REGISTERING YOUR COPY
  137.  
  138.         Registration of your copy of the LiteComm ToolBox provides you 
  139.         with several benefits:
  140.  
  141.              1. Puts you on our mailing list for low-cost updates and 
  142.              enhancements, when they occur.
  143.  
  144.              2. Gives you access to telephone support. Sorry, but we 
  145.              cannot provide support by telephone to unregistered user's 
  146.              of the ToolBox. Unregistered users can leave EMAIL on 
  147.              Compuserve to 70166,1152; on GEnie to I.TECH; and on DELPHI 
  148.              to RBMACE. We will respond to EMAIL on an as-available 
  149.              basis.
  150.  
  151.              3. Helps to further the shareware concept.
  152.  
  153.         To register your copy, use the form at the end of this 
  154.         documentation.
  155.  
  156.                                       NOTE
  157.  
  158.         We are already planning enhancements to this product. The first 
  159.         to be released will be a super-efficient XMODEM engine for file 
  160.         transfers, followed by similar engines for CompuServe B and 
  161.         Kermit protocols. These engines, as they are released, will only 
  162.         be made available to registered ToolBox users. The small model 
  163.         library, as enhanced but without the protocol engines, will 
  164.         continue to be offered as shareware.
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.                 Copyright (c) 1987 Information Technology, Ltd.
  194.  
  195.  
  196.  
  197.  
  198.  
  199.                   LiteComm Toolbox for Datalight and Turbo C
  200.  
  201.  
  202.         COMMUNICATIONS AND THE PC
  203.  
  204.         This section is intended as a mini-tutorial on commumnications 
  205.         concepts. We encourage you to read it, although it is not 
  206.         strictly necessary to do so.
  207.  
  208.         The IBM-PC, and its close compatables, is a generally well 
  209.         thought-out, flexible, and well-executed computer. 
  210.         Unfortunately, not as much can be said for the thought which was 
  211.         given to the software which is meant to provide access to that 
  212.         hardware. One of the shortcomings which is most noticable is in 
  213.         the support, or rather lack of it, that is provided to handle 
  214.         access to the serial port. Support for the serial port is 
  215.         limited by the BIOS to polled mode only, i.e. a program must 
  216.         interrogate the port on a regular basis to avoid losing received 
  217.         characters, and to check to determine whether or not the port is 
  218.         ready to send a character. Not only is this mode of operation 
  219.         primitive; it also tends to cause complications when attempting 
  220.         to perform any but the simplest of tasks.
  221.  
  222.         A novice might think that the hardware, in some way, is the 
  223.         limiting factor. In fact, everything that is needed, hardware-
  224.         wise, to support a more sophisticated method of handling the 
  225.         serial port is already there. All we are missing is the software 
  226.         follow-through. The LiteComm ToolBox provides this missing 
  227.         software.
  228.  
  229.         The term serial port comes from the fact that both incoming and 
  230.         outgoing characters entering and leaving the port do so in a 
  231.         bitwise fashion. When we send a character out the serial port, 
  232.         the responsible circuitry sends out information one bit at a 
  233.         time. When we receive a character, this circuitry accepts the 
  234.         individual bits and reassembles them into a recognizable 
  235.         character. These very complex operations are performed 
  236.         automatically by the 8250 UART (Universal Asynchronous Receiver-
  237.         Transmitter).
  238.  
  239.         The 8250 UART is a fully programmable device that permits 
  240.         independant control of the various parameters that affect 
  241.         serial communications, i.e. baud rate, parity, number of data 
  242.         bits, and number of stop bits. The 8250 also optionally supports 
  243.         four types of interrupts, error/break detection, modem status 
  244.         change detection, transmitter ready, and received character 
  245.         ready. The LiteComm ToolBox fully supports all four type of 
  246.         interrupts.
  247.  
  248.         The term "asynchronous" implies that there is no timing 
  249.         associated with the transmission of information. Instead, the 
  250.         "clocking-in" of the data bits is done by counting the bits. The 
  251.         first bit sent or received is call the start bit and signals the 
  252.         beginning of a new character. The individual data bits follow 
  253.         the start bit which are clocked out and in at the specified data 
  254.         rate, with the least significant bit transferred first and the 
  255.         parity bit, if present, transferred last. Finally one or more 
  256.         stop bits follow, signalling the end of the character.
  257.  
  258.  
  259.                 Copyright (c) 1987 Information Technology, Ltd.
  260.  
  261.  
  262.  
  263.  
  264.  
  265.                   LiteComm Toolbox for Datalight and Turbo C
  266.  
  267.  
  268.  
  269.         The 8250 UART takes care of all of the mechanics associated with 
  270.         the process described in the preceeding paragraph. The UART will 
  271.         also detect and report error which may occur in the process. For 
  272.         example, if the parity bit is incorrect, the UART reports the 
  273.         fact. If too few or too many bits are received, the UART will 
  274.         report a framing error or overrun error respectivally.
  275.  
  276.         Since the transmission of information may depend on complex 
  277.         interactions with another device, such as a modem or computer, 
  278.         the 8250 can also report on the status of the "handshaking" lines 
  279.         used to provide information about the status of the connection 
  280.         with the other device. These signals are explained below:
  281.  
  282.               SIGNAL DESCRIPTION
  283.  
  284.                  CTS Clear To Send - The other device 
  285.                                will accept a transmission.
  286.  
  287.                  DSR Data Set Ready - The other device 
  288.                                is enabled.
  289.  
  290.                  RI Ring Indicator - Usually reserved
  291.                                for modems only. The phone is 
  292.                                ringing.
  293.  
  294.                  DCD Data Carrier Detect - Usually re-
  295.                                served for modems. The other 
  296.                                modem's carrier signal was 
  297.                                detected.
  298.  
  299.         The header file for the LiteComm ToolBox contains the various bit 
  300.         masks required for you to make use of the information provided by 
  301.         the 8250 UART.
  302.  
  303.  
  304.  
  305.  
  306.  
  307.  
  308.  
  309.  
  310.  
  311.  
  312.  
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.                 Copyright (c) 1987 Information Technology, Ltd.
  326.  
  327.  
  328.  
  329.  
  330.  
  331.                   LiteComm Toolbox for Datalight and Turbo C
  332.  
  333.  
  334.         DO's and DONT's of the ToolBox
  335.  
  336.         Before you can send or receive information on a serial port using 
  337.         the ToolBox, you must use the open function to enable the line. 
  338.         This function initializes the 8250 UART with the correct 
  339.         parameters, and introduces the UART into the interrupt structure 
  340.         of the PC. The ToolBox will detect, and report, any errors that 
  341.         you may make in selecting the port or specifying the initial 
  342.         parameters. The ToolBox cannot and will not detect an attempt to 
  343.         open a non-existant serial port.
  344.  
  345.         The ToolBox interfaces directly with the interrupt structure of 
  346.         the PC. It is critical that, before exiting a program that has 
  347.         opened a serial port that the serial port is closed with the 
  348.         close function. If you exit your program without closing the 
  349.         port, you may cause you system to crash since the interrupt 
  350.         vector for the port might point to a section of memory that no 
  351.         longer contains the needed code to support the interrupt.
  352.  
  353.         Failure of the open function can be the result of either improper 
  354.         parameters to the open function, or insufficient memory available 
  355.         to allocate the requested buffers and related control structures 
  356.         for the port. Memory for the transmit and receive buffers as 
  357.         well as the port control block are allocated from free memory. 
  358.         It is your responsibility to insure that adequate memory is 
  359.         available for this purpose.
  360.  
  361.         Unless you are very familiar with the interrupt structure of the 
  362.         PC, do not attempt to manipulate the interrupt enable flag 
  363.         outside of the ToolBox. The ToolBox sets and clears the 
  364.         interrupt enable flag at appropriate times and assumes that it 
  365.         has sole control over the flag.
  366.  
  367.         Unless otherwise specified, all library functions have been 
  368.         compiled with the default alignment, i.e. the structure alignment 
  369.         switch has not been used in creating the ToolBox library.
  370.  
  371.  
  372.  
  373.  
  374.  
  375.  
  376.  
  377.  
  378.  
  379.  
  380.  
  381.  
  382.  
  383.  
  384.  
  385.  
  386.  
  387.  
  388.  
  389.  
  390.  
  391.                 Copyright (c) 1987 Information Technology, Ltd.
  392.  
  393.  
  394.  
  395.  
  396.  
  397.                   LiteComm Toolbox for Datalight and Turbo C
  398.  
  399.  
  400.                                NEW IN VERSION 1.1
  401.  
  402.         With version 1.1 we have made several changes of signifigance. 
  403.         The ToolBox now fully supports both COM3 and COM4, in addition to 
  404.         COM1 and COM2. Within certain restrictions, and dependant upon 
  405.         the particular system, it is now possible to handle interrupt-
  406.         driven communications on all four ports simultaneously. See the 
  407.         section GOING PAST COM2 for additional details.
  408.  
  409.         Version 1.1 of the ToolBox has also been shrunk by some using 
  410.         some different techniques in the kernel, and by changing the 
  411.         organization of the library itself. Please be aware that change 
  412.         have been made to the litecomm.h file which require that 
  413.         applications using the ToolBox be recompiled and re-linked.
  414.  
  415.  
  416.  
  417.  
  418.  
  419.  
  420.  
  421.  
  422.  
  423.  
  424.  
  425.  
  426.  
  427.  
  428.  
  429.  
  430.  
  431.  
  432.  
  433.  
  434.  
  435.  
  436.  
  437.  
  438.  
  439.  
  440.  
  441.  
  442.  
  443.  
  444.  
  445.  
  446.  
  447.  
  448.  
  449.  
  450.  
  451.  
  452.  
  453.  
  454.  
  455.  
  456.  
  457.                 Copyright (c) 1987 Information Technology, Ltd.
  458.  
  459.  
  460.  
  461.  
  462.  
  463.                   LiteComm Toolbox for Datalight and Turbo C
  464.  
  465.  
  466.                                NEW IN VERSION 1.2
  467.  
  468.         Version 1.2 adds 21 new functions designed to aid you in the use 
  469.         of Hayes and Hayes compatible modems. It is not the intent of 
  470.         these new functions to replace your knowledge of the Hayes 
  471.         command set, but rather to augment it by relieving the burden of 
  472.         re-inventing the wheel. In our experience, the most successful 
  473.         programs rely heavily upon the use of pre-written and proven 
  474.         modules. The new functions provide just such capability.
  475.  
  476.         As with the original ToolBox functions, the new functions do 
  477.         error checking, where appropriate. They will not, however, 
  478.         prevent you from feeding a modem a set of nonsense or conflicting 
  479.         commands. It is your responsibility to insure that the commands 
  480.         you are issuing to the modem make sense. Therefore, when you are 
  481.         using the modem-related function, we strongly urge you to check 
  482.         the modem result codes, unless you've turned them off of course.
  483.  
  484.  
  485.  
  486.  
  487.  
  488.  
  489.  
  490.  
  491.  
  492.  
  493.  
  494.  
  495.  
  496.  
  497.  
  498.  
  499.  
  500.  
  501.  
  502.  
  503.  
  504.  
  505.  
  506.  
  507.  
  508.  
  509.  
  510.  
  511.  
  512.  
  513.  
  514.  
  515.  
  516.  
  517.  
  518.  
  519.  
  520.  
  521.  
  522.  
  523.                 Copyright (c) 1987 Information Technology, Ltd.
  524.  
  525.  
  526.  
  527.  
  528.  
  529.                   LiteComm Toolbox for Datalight and Turbo C
  530.  
  531.  
  532.                                NEW IN VERSION 2.0
  533.  
  534.         With version 2.0 of LiteComm, we have added several new functions 
  535.         and announce the availability, to registered users, of the xmodem 
  536.         engine promised when LiteComm was first released. We have 
  537.         included, as part of the shareware version a copy of the 
  538.         documenation for LXM (LiteComm XModem), as well as a sample 
  539.         program, SCE, that demonstrates the use of the engine.
  540.  
  541.         The new functions added to the library include lc_peek, a one 
  542.         character look-ahead function into the input buffer, and several 
  543.         functions developed for use with LXM that provide programmable 
  544.         interval timer capabailities.
  545.  
  546.         Registrants of version 1.XX of LiteComm will receive the the LXM 
  547.         engine automatically.
  548.  
  549.  
  550.  
  551.  
  552.  
  553.  
  554.  
  555.  
  556.  
  557.  
  558.  
  559.  
  560.  
  561.  
  562.  
  563.  
  564.  
  565.  
  566.  
  567.  
  568.  
  569.  
  570.  
  571.  
  572.  
  573.  
  574.  
  575.  
  576.  
  577.  
  578.  
  579.  
  580.  
  581.  
  582.  
  583.  
  584.  
  585.  
  586.  
  587.  
  588.  
  589.                 Copyright (c) 1987 Information Technology, Ltd.
  590.  
  591.  
  592.  
  593.  
  594.  
  595.                   LiteComm Toolbox for Datalight and Turbo C
  596.  
  597.  
  598.                                  GOING PAST COM2
  599.  
  600.         In the design of the original PC, and in subsequent variations 
  601.         such as the PC/AT, there were only provision for two serial 
  602.         ports. Many manufacturers of add-in products, both serial ports 
  603.         and internal modems have added the capability to support 1 or 
  604.         more additional ports beyond the COM2 limit. Generally, this can 
  605.         cause problems in the PC since there is no room in the interrupt 
  606.         request scheme for additional levels of interrupts, and there are 
  607.         no designated interrupt vector for other additional ports.
  608.  
  609.         The ToolBox approach to resolving these issues is to permit the 
  610.         programmer a degree of control over the parameters that govern 
  611.         the interrupt mechanism for COM3 and COM4. Specifically, these 
  612.         parameters are: 1) the interrupt request (IRQ) bit that is used 
  613.         to mask the 8259 interrupt controller; 2) the interrupt vector 
  614.         number (not address) to which the port is attached; and 3) the 
  615.         base i/o register for the port itself. Of course, it is assumed 
  616.         that the port is based upon the 8250 UART or compatible device.
  617.  
  618.         Before you attempt to use COM3 and/or COM4, you must determine 
  619.         from the port's documentation, the appropriate values for these 
  620.         three parameters. As distributed, the ToolBox assumes the 
  621.         following:
  622.  
  623.                             COM3 COM4
  624.  
  625.              IRQ Bit 4 3
  626.  
  627.              Vector # 0Ch 0Bh
  628.  
  629.              Base Reg 3E8h 2E8h
  630.  
  631.         You may change any or all of these values by using the _portchg 
  632.         function described below, but only before you open the port with 
  633.         comm_opn. Once the port has been opened, _portchg is 
  634.         ineffective, and _portchg will not work on COM1 or COM2.
  635.  
  636.         CAUTION
  637.         As you can see from the above, COM3 and COM4 share two critical 
  638.         parameters with COM1 and COM2 respectively, the IRQ bit and the 
  639.         interrupt vector number. If you intend to use COM1 and COM3 or 
  640.         COM2 and COM4 simultaneously, you must change the vector number 
  641.         for COM3 or COM4 to an unused vector. The ability for your add-
  642.         on ports to handle such a change is highly hardware dependant, so 
  643.         check your port's documentation carefully. Failure to do so will 
  644.         result in loss of data at best, and a system lockup at worst. 
  645.  
  646.  
  647.  
  648.  
  649.  
  650.  
  651.  
  652.  
  653.  
  654.  
  655.                 Copyright (c) 1987 Information Technology, Ltd.
  656.  
  657.  
  658.  
  659.  
  660.  
  661.                   LiteComm Toolbox for Datalight and Turbo C
  662.  
  663.  
  664.         FUNCTION _portchg
  665.  
  666.         SUMMARY
  667.  
  668.         #include <litecomm.h>
  669.  
  670.         int _portchg(port, base, irq, vector)
  671.  
  672.              unsigned port;
  673.              unsigned base;
  674.              unsigned vector;
  675.              char irq;
  676.  
  677.         DESCRIPTION
  678.  
  679.         Changes one or more of the critical parameters for COM3 or COM4. 
  680.         This function must be used before the port is opened to be 
  681.         effective. To leave any of the parameters at its default value, 
  682.         make the corresponding entry 0. Note that vector is a vector 
  683.         number, not and address or pointer.
  684.          
  685.         The default parameters are shown in the litecomm.h include file.
  686.  
  687.  
  688.         EXAMPLE
  689.  
  690.          if (_portchg(port, 0x408, 0, 0, 0) == -1)
  691.          {
  692.              printf("Error Changing Port %d\n", port);
  693.              exit(1);
  694.          }
  695.  
  696.         RETURN VALUES
  697.  
  698.         Returns 0 if the function is successful, -1 if you attempt to 
  699.         change a port other that 3 or 4.
  700.  
  701.  
  702.  
  703.  
  704.  
  705.  
  706.  
  707.  
  708.  
  709.  
  710.  
  711.  
  712.  
  713.  
  714.  
  715.  
  716.  
  717.  
  718.  
  719.  
  720.  
  721.                 Copyright (c) 1987 Information Technology, Ltd.
  722.  
  723.  
  724.  
  725.  
  726.  
  727.                   LiteComm Toolbox for Datalight and Turbo C
  728.  
  729.  
  730.         FUNCTION comm_opn
  731.  
  732.         SUMMARY
  733.  
  734.         #include <litecomm.h>
  735.  
  736.         int comm_opn(port, baud, parity, datab, stopb, inbufsz, outbufsz)
  737.  
  738.              unsigned port;
  739.              unsigned baud;
  740.              unsigned parity;
  741.              unsigned datab;
  742.              unsigned stopb;
  743.              unsigned inbufsz;
  744.              unsigned outbufsz;
  745.  
  746.         DESCRIPTION
  747.  
  748.         Opens the specified port for use and attaches an interrupt 
  749.         handler to DOS for the port. The function allocates buffers for 
  750.         input and output of the specified sizes, and sets the port to the 
  751.         parameters specified. The minimum value for inbufsz is 128; the 
  752.         minimum size for outbufsz is 64. A port opened in this manner 
  753.         must be closed using comm_close before program termination to 
  754.         avoid the possibility of a system crash.
  755.  
  756.         The parameters passed to the function should be from the 
  757.         parameter set in the litecomm.h include file.
  758.  
  759.  
  760.         EXAMPLE
  761.  
  762.          if (comm_opn(port, B1200, NPARITY, BIT8, STOP1, 256, 256) == -1)
  763.          {
  764.              printf("Error Opening Port %d\n", port);
  765.              exit(1);
  766.          }
  767.  
  768.         RETURN VALUES
  769.  
  770.              Upon successful open, the function returns port. If any 
  771.              error occurs, regardless of type, the function returns -1.
  772.  
  773.  
  774.  
  775.  
  776.  
  777.  
  778.  
  779.  
  780.  
  781.  
  782.  
  783.  
  784.  
  785.  
  786.  
  787.                 Copyright (c) 1987 Information Technology, Ltd.
  788.  
  789.  
  790.  
  791.  
  792.  
  793.                   LiteComm Toolbox for Datalight and Turbo C
  794.  
  795.  
  796.         FUNCTION comm_close
  797.  
  798.         SUMMARY
  799.  
  800.         #include <litecomm.h>
  801.  
  802.         int comm_close(port)
  803.  
  804.              unsigned port;
  805.  
  806.         DESCRIPTION
  807.  
  808.              This function is the companion to comm_opn and, in effect, 
  809.              performs the opposite action. Comm_close detaches the 
  810.              library routines from the interrupt handler, and reconnects 
  811.              the previous interrupt handler. Comm_close also release 
  812.              dynamically allocated member used for buffering and control 
  813.              structures. Failure to call comm_close before terminating a 
  814.              program may result in unexplained system crashes or hangs.
  815.  
  816.         RETURN VALUES
  817.  
  818.              If any error occurs, regardless of type, the function 
  819.              returns -1.
  820.  
  821.  
  822.  
  823.  
  824.  
  825.  
  826.  
  827.  
  828.  
  829.  
  830.  
  831.  
  832.  
  833.  
  834.  
  835.  
  836.  
  837.  
  838.  
  839.  
  840.  
  841.  
  842.  
  843.  
  844.  
  845.  
  846.  
  847.  
  848.  
  849.  
  850.  
  851.  
  852.  
  853.                 Copyright (c) 1987 Information Technology, Ltd.
  854.  
  855.  
  856.  
  857.  
  858.  
  859.                   LiteComm Toolbox for Datalight and Turbo C
  860.  
  861.  
  862.         FUNCTION comm_setup
  863.  
  864.         SUMMARY
  865.  
  866.         #include <litecomm.h>
  867.  
  868.         int comm_setup(port,baud,parity,datab,stopb)
  869.  
  870.              unsigned port;
  871.              unsigned baud;
  872.              unsigned parity;
  873.              unsigned datab;
  874.              unsigned stopb;
  875.  
  876.  
  877.         DESCRIPTION
  878.  
  879.              The comm_setup function is a subset of the comm_opn function 
  880.              and the remarks made in the description of comm_opn apply. 
  881.              This function is useful if you wish to change the basic 
  882.              communication parameters of the specified port that has 
  883.              already been opened without comm_close'ing the port and 
  884.              breaking the telephone connection.
  885.  
  886.         EXAMPLE
  887.  
  888.              if (comm_setup(port, B1200, NPARITY, BIT8, STOP1) == -1)
  889.              {
  890.                  printf("Error Changing Port %d\n", port);
  891.                  exit(1);
  892.              }
  893.  
  894.         RETURN VALUES
  895.  
  896.              If any error occurs, regardless of type, the function 
  897.              returns -1.
  898.  
  899.         SEE ALSO
  900.              comm_opn
  901.  
  902.  
  903.  
  904.  
  905.  
  906.  
  907.  
  908.  
  909.  
  910.  
  911.  
  912.  
  913.  
  914.  
  915.  
  916.  
  917.  
  918.  
  919.                 Copyright (c) 1987 Information Technology, Ltd.
  920.  
  921.  
  922.  
  923.  
  924.  
  925.                   LiteComm Toolbox for Datalight and Turbo C
  926.  
  927.  
  928.         FUNCTION lc_vport
  929.  
  930.         SUMMARY
  931.  
  932.         #include <litecomm.h>
  933.  
  934.         COMM *lc_vport(port)
  935.  
  936.              unsigned port;
  937.  
  938.  
  939.         DESCRIPTION
  940.  
  941.              Used internally to validate that the port number specified 
  942.              is correct and has been opened with the comm_opn function. 
  943.              May be of use to you in writing certain applications.
  944.  
  945.         RETURN VALUES
  946.  
  947.              If the port is valid and has been opened, returns a pointer 
  948.              to the control block for the port. Returns NULL if an error 
  949.              occurs;
  950.          
  951.  
  952.  
  953.  
  954.  
  955.  
  956.  
  957.  
  958.  
  959.  
  960.  
  961.  
  962.  
  963.  
  964.  
  965.  
  966.  
  967.  
  968.  
  969.  
  970.  
  971.  
  972.  
  973.  
  974.  
  975.  
  976.  
  977.  
  978.  
  979.  
  980.  
  981.  
  982.  
  983.  
  984.  
  985.                 Copyright (c) 1987 Information Technology, Ltd.
  986.  
  987.  
  988.  
  989.  
  990.  
  991.                   LiteComm Toolbox for Datalight and Turbo C
  992.  
  993.  
  994.         FUNCTION lc_icnt
  995.  
  996.         SUMMARY
  997.  
  998.         #include <litecomm.h>
  999.  
  1000.         int lc_icnt(port)
  1001.  
  1002.              unsigned port;
  1003.  
  1004.  
  1005.         DESCRIPTION
  1006.  
  1007.              May be used to determine the number of characters currently 
  1008.              in the input buffer for the port. 
  1009.  
  1010.         RETURN VALUES
  1011.  
  1012.              If the port is valid and has been opened, returns the number 
  1013.              of character in the port's input buffer. Returns -1 if an 
  1014.              error occurs;
  1015.          
  1016.  
  1017.  
  1018.  
  1019.  
  1020.  
  1021.  
  1022.  
  1023.  
  1024.  
  1025.  
  1026.  
  1027.  
  1028.  
  1029.  
  1030.  
  1031.  
  1032.  
  1033.  
  1034.  
  1035.  
  1036.  
  1037.  
  1038.  
  1039.  
  1040.  
  1041.  
  1042.  
  1043.  
  1044.  
  1045.  
  1046.  
  1047.  
  1048.  
  1049.  
  1050.  
  1051.                 Copyright (c) 1987 Information Technology, Ltd.
  1052.  
  1053.  
  1054.  
  1055.  
  1056.  
  1057.                   LiteComm Toolbox for Datalight and Turbo C
  1058.  
  1059.  
  1060.         FUNCTION lc_mstat
  1061.  
  1062.         SUMMARY
  1063.  
  1064.         #include <litecomm.h>
  1065.  
  1066.         int lc_mstat(port)
  1067.  
  1068.              unsigned port;
  1069.  
  1070.  
  1071.         DESCRIPTION
  1072.  
  1073.              May be used to determine the last known state of the modem-
  1074.              supplied handshake signals. These may be tested using the 
  1075.              values in the include'd litecomm.h file.
  1076.  
  1077.         RETURN VALUES
  1078.  
  1079.              If the port is valid and has been opened, returns the 
  1080.              current modem status bits. Returns -1 if an error occurs;
  1081.          
  1082.  
  1083.  
  1084.  
  1085.  
  1086.  
  1087.  
  1088.  
  1089.  
  1090.  
  1091.  
  1092.  
  1093.  
  1094.  
  1095.  
  1096.  
  1097.  
  1098.  
  1099.  
  1100.  
  1101.  
  1102.  
  1103.  
  1104.  
  1105.  
  1106.  
  1107.  
  1108.  
  1109.  
  1110.  
  1111.  
  1112.  
  1113.  
  1114.  
  1115.  
  1116.  
  1117.                 Copyright (c) 1987 Information Technology, Ltd.
  1118.  
  1119.  
  1120.  
  1121.  
  1122.  
  1123.                   LiteComm Toolbox for Datalight and Turbo C
  1124.  
  1125.  
  1126.         FUNCTION lc_estat
  1127.  
  1128.         SUMMARY
  1129.  
  1130.         #include <litecomm.h>
  1131.  
  1132.         int lc_estat(port)
  1133.  
  1134.              unsigned port;
  1135.  
  1136.  
  1137.         DESCRIPTION
  1138.  
  1139.              May be used to determine the last known state of the serial 
  1140.              port's error status bits. These may be tested using the 
  1141.              values in the include'd litecomm.h file.
  1142.  
  1143.         RETURN VALUES
  1144.  
  1145.              If the port is valid and has been opened, returns the 
  1146.              current error status bits. Returns -1 if an error occurs;
  1147.          
  1148.  
  1149.  
  1150.  
  1151.  
  1152.  
  1153.  
  1154.  
  1155.  
  1156.  
  1157.  
  1158.  
  1159.  
  1160.  
  1161.  
  1162.  
  1163.  
  1164.  
  1165.  
  1166.  
  1167.  
  1168.  
  1169.  
  1170.  
  1171.  
  1172.  
  1173.  
  1174.  
  1175.  
  1176.  
  1177.  
  1178.  
  1179.  
  1180.  
  1181.  
  1182.  
  1183.                 Copyright (c) 1987 Information Technology, Ltd.
  1184.  
  1185.  
  1186.  
  1187.  
  1188.  
  1189.                   LiteComm Toolbox for Datalight and Turbo C
  1190.  
  1191.  
  1192.         FUNCTION lc_getw
  1193.  
  1194.         SUMMARY
  1195.  
  1196.         #include <litecomm.h>
  1197.  
  1198.         int lc_getw(port)
  1199.  
  1200.              unsigned port;
  1201.  
  1202.  
  1203.         DESCRIPTION
  1204.  
  1205.              Read a character from the serial port's input buffer. Pend 
  1206.              idefinitely until a character is available.
  1207.  
  1208.         RETURN VALUES
  1209.  
  1210.              Returns the next available character in the input buffer for 
  1211.              the port. Returns -1 if the port is not active.
  1212.          
  1213.  
  1214.  
  1215.  
  1216.  
  1217.  
  1218.  
  1219.  
  1220.  
  1221.  
  1222.  
  1223.  
  1224.  
  1225.  
  1226.  
  1227.  
  1228.  
  1229.  
  1230.  
  1231.  
  1232.  
  1233.  
  1234.  
  1235.  
  1236.  
  1237.  
  1238.  
  1239.  
  1240.  
  1241.  
  1242.  
  1243.  
  1244.  
  1245.  
  1246.  
  1247.  
  1248.  
  1249.                 Copyright (c) 1987 Information Technology, Ltd.
  1250.  
  1251.  
  1252.  
  1253.  
  1254.  
  1255.                   LiteComm Toolbox for Datalight and Turbo C
  1256.  
  1257.  
  1258.         FUNCTION lc_setmdm
  1259.  
  1260.         SUMMARY
  1261.  
  1262.         #include <litecomm.h>
  1263.  
  1264.         int lc_setmdm(port, newset)
  1265.  
  1266.              unsigned port;
  1267.              unsigned newset;
  1268.  
  1269.         DESCRIPTION
  1270.  
  1271.              Set one or more of the modem control signals. Because of 
  1272.              the need to always have OUT2 set for interrupt support, the 
  1273.              function always provides the correct setting for this bit. 
  1274.              Use the values found in the include file.
  1275.  
  1276.         RETURN VALUES
  1277.  
  1278.              Returns 0 if the operation was successful, returns -1 
  1279.              otherwise.
  1280.  
  1281.         SEE ALSO
  1282.  
  1283.              lc_clrmdm, lc_togmdm 
  1284.  
  1285.  
  1286.  
  1287.  
  1288.  
  1289.  
  1290.  
  1291.  
  1292.  
  1293.  
  1294.  
  1295.  
  1296.  
  1297.  
  1298.  
  1299.  
  1300.  
  1301.  
  1302.  
  1303.  
  1304.  
  1305.  
  1306.  
  1307.  
  1308.  
  1309.  
  1310.  
  1311.  
  1312.  
  1313.  
  1314.  
  1315.                 Copyright (c) 1987 Information Technology, Ltd.
  1316.  
  1317.  
  1318.  
  1319.  
  1320.  
  1321.                   LiteComm Toolbox for Datalight and Turbo C
  1322.  
  1323.  
  1324.         FUNCTION lc_clrmdm
  1325.  
  1326.         SUMMARY
  1327.  
  1328.         #include <litecomm.h>
  1329.  
  1330.         int lc_clrmdm(port, newset)
  1331.  
  1332.              unsigned port;
  1333.              unsigned newset;
  1334.  
  1335.         DESCRIPTION
  1336.  
  1337.              Companion to setmdm function. Clears one or more of the 
  1338.              modem control signals. Because of the need to always have 
  1339.              OUT2 set for interrupt support, the function always provides 
  1340.              the correct setting for this bit. Use the values found in 
  1341.              the include file.
  1342.  
  1343.         RETURN VALUES
  1344.  
  1345.              Returns 0 if the operation was successful, returns -1 
  1346.              otherwise.
  1347.  
  1348.         SEE ALSO
  1349.  
  1350.              lc_setmdm, lc_togmdm 
  1351.  
  1352.  
  1353.  
  1354.  
  1355.  
  1356.  
  1357.  
  1358.  
  1359.  
  1360.  
  1361.  
  1362.  
  1363.  
  1364.  
  1365.  
  1366.  
  1367.  
  1368.  
  1369.  
  1370.  
  1371.  
  1372.  
  1373.  
  1374.  
  1375.  
  1376.  
  1377.  
  1378.  
  1379.  
  1380.  
  1381.                 Copyright (c) 1987 Information Technology, Ltd.
  1382.  
  1383.  
  1384.  
  1385.  
  1386.  
  1387.                   LiteComm Toolbox for Datalight and Turbo C
  1388.  
  1389.  
  1390.         FUNCTION lc_togmdm
  1391.  
  1392.         SUMMARY
  1393.  
  1394.         #include <litecomm.h>
  1395.  
  1396.         int lc_togmdm(port, newset)
  1397.  
  1398.              unsigned port;
  1399.              unsigned newset;
  1400.  
  1401.         DESCRIPTION
  1402.  
  1403.              Companion to setmdm function. Flip-flops one or more of the 
  1404.              modem control signals. Because of the need to always have 
  1405.              OUT2 set for interrupt support, the function always provides 
  1406.              the correct setting for this bit. Use the values found in 
  1407.              the include file.
  1408.  
  1409.         RETURN VALUES
  1410.  
  1411.              Returns 0 if the operation was successful, returns -1 
  1412.              otherwise.
  1413.  
  1414.         SEE ALSO
  1415.  
  1416.              lc_setmdm, lc_clrmdm 
  1417.  
  1418.  
  1419.  
  1420.  
  1421.  
  1422.  
  1423.  
  1424.  
  1425.  
  1426.  
  1427.  
  1428.  
  1429.  
  1430.  
  1431.  
  1432.  
  1433.  
  1434.  
  1435.  
  1436.  
  1437.  
  1438.  
  1439.  
  1440.  
  1441.  
  1442.  
  1443.  
  1444.  
  1445.  
  1446.  
  1447.                 Copyright (c) 1987 Information Technology, Ltd.
  1448.  
  1449.  
  1450.  
  1451.  
  1452.  
  1453.                   LiteComm Toolbox for Datalight and Turbo C
  1454.  
  1455.  
  1456.         FUNCTION lc_xoff
  1457.  
  1458.         SUMMARY
  1459.  
  1460.         #include <litecomm.h>
  1461.  
  1462.         int lc_xoff(port, flag)
  1463.  
  1464.              unsigned port;
  1465.              BOOL flag; /* #define BOOL int */
  1466.  
  1467.         DESCRIPTION
  1468.  
  1469.              If flag is TRUE, turns on semi-automatic XON-XOFF flow 
  1470.              control function. If flag is FALSE (the default setting), 
  1471.              automatic flow control is disabled. When enabled, the comm 
  1472.              handler will automatically transmit an XOFF if and when the 
  1473.              input buffer is approximately 2/3 full and will 
  1474.              automatically recognize an XOFF sent by the companion 
  1475.              system. If the companion system transmits an XOFF, the comm 
  1476.              handler will refuse to send any characters until the 
  1477.              condition is cleared.
  1478.  
  1479.              It is the programmer's responsibility to transmit XON when 
  1480.              conditions permit. See the lc_putxoff function to tell if 
  1481.              an automatic XOFF has been sent by the comm handler. See 
  1482.              the lc_gotxoff function to see if the companion system has 
  1483.              sent an XOFF.
  1484.  
  1485.              If you intended to impliment a protocol that might include 
  1486.              the XON-XOFF characters, be sure to disable the automatic 
  1487.              flow control. Failure to do so may result in a system hang.
  1488.  
  1489.         RETURN VALUES
  1490.  
  1491.              Returns 0 if the operation was successful, returns -1 
  1492.              otherwise.
  1493.  
  1494.         SEE ALSO
  1495.  
  1496.              lc_gotxoff, lc_putxoff 
  1497.  
  1498.  
  1499.  
  1500.  
  1501.  
  1502.  
  1503.  
  1504.  
  1505.  
  1506.  
  1507.  
  1508.  
  1509.  
  1510.  
  1511.  
  1512.  
  1513.                 Copyright (c) 1987 Information Technology, Ltd.
  1514.  
  1515.  
  1516.  
  1517.  
  1518.  
  1519.                   LiteComm Toolbox for Datalight and Turbo C
  1520.  
  1521.  
  1522.         FUNCTION lc_gotxoff
  1523.  
  1524.         SUMMARY
  1525.  
  1526.         #include <litecomm.h>
  1527.  
  1528.         BOOL lc_gotxoff(port)
  1529.  
  1530.              unsigned port;
  1531.         /* #define BOOL int */
  1532.  
  1533.         DESCRIPTION
  1534.  
  1535.              See below for the values returned. If an XOFF has been 
  1536.              received, the port's flag will be reset, and transmission to 
  1537.              the companion system will be permitted.
  1538.  
  1539.         RETURN VALUES
  1540.  
  1541.              Returns TRUE if XOFF received from the companion system, 
  1542.              FALSE if XOFF not received. Will return -1 in the case of 
  1543.              an error.
  1544.  
  1545.         SEE ALSO
  1546.  
  1547.              lc_xoff, lc_putxoff 
  1548.  
  1549.  
  1550.  
  1551.  
  1552.  
  1553.  
  1554.  
  1555.  
  1556.  
  1557.  
  1558.  
  1559.  
  1560.  
  1561.  
  1562.  
  1563.  
  1564.  
  1565.  
  1566.  
  1567.  
  1568.  
  1569.  
  1570.  
  1571.  
  1572.  
  1573.  
  1574.  
  1575.  
  1576.  
  1577.  
  1578.  
  1579.                 Copyright (c) 1987 Information Technology, Ltd.
  1580.  
  1581.  
  1582.  
  1583.  
  1584.  
  1585.                   LiteComm Toolbox for Datalight and Turbo C
  1586.  
  1587.  
  1588.         FUNCTION lc_putxoff
  1589.  
  1590.         SUMMARY
  1591.  
  1592.         #include <litecomm.h>
  1593.  
  1594.         BOOL lc_putxoff(port)
  1595.  
  1596.              unsigned port;
  1597.         /* #define BOOL int */
  1598.  
  1599.         DESCRIPTION
  1600.  
  1601.              See below for the values returned. If an XOFF has been 
  1602.              sent, the port's flag will be reset. Use this function in 
  1603.              concert with transmission of an XON character to the 
  1604.              companion system to permit transmissions to proceed. 
  1605.  
  1606.         RETURN VALUES
  1607.  
  1608.              Returns TRUE if XOFF was sent to the companion system, 
  1609.              FALSE if XOFF not sent since the last time the function was 
  1610.              called. Will return -1 in the case of an error.
  1611.  
  1612.         SEE ALSO
  1613.  
  1614.              lc_xoff, lc_putxoff 
  1615.  
  1616.  
  1617.  
  1618.  
  1619.  
  1620.  
  1621.  
  1622.  
  1623.  
  1624.  
  1625.  
  1626.  
  1627.  
  1628.  
  1629.  
  1630.  
  1631.  
  1632.  
  1633.  
  1634.  
  1635.  
  1636.  
  1637.  
  1638.  
  1639.  
  1640.  
  1641.  
  1642.  
  1643.  
  1644.  
  1645.                 Copyright (c) 1987 Information Technology, Ltd.
  1646.  
  1647.  
  1648.  
  1649.  
  1650.  
  1651.                   LiteComm Toolbox for Datalight and Turbo C
  1652.  
  1653.  
  1654.         FUNCTION lc_get
  1655.  
  1656.         SUMMARY
  1657.  
  1658.         #include <litecomm.h>
  1659.  
  1660.         int lc_get(port)
  1661.  
  1662.              unsigned port;
  1663.  
  1664.  
  1665.         DESCRIPTION
  1666.  
  1667.              Read a character from the serial port's input buffer.
  1668.  
  1669.         RETURN VALUES
  1670.  
  1671.              Returns the next available character in the input buffer for 
  1672.              the port. Returns -1 if the port is not active, or if there 
  1673.              are not characters in the port's buffer.
  1674.          
  1675.  
  1676.  
  1677.  
  1678.  
  1679.  
  1680.  
  1681.  
  1682.  
  1683.  
  1684.  
  1685.  
  1686.  
  1687.  
  1688.  
  1689.  
  1690.  
  1691.  
  1692.  
  1693.  
  1694.  
  1695.  
  1696.  
  1697.  
  1698.  
  1699.  
  1700.  
  1701.  
  1702.  
  1703.  
  1704.  
  1705.  
  1706.  
  1707.  
  1708.  
  1709.  
  1710.  
  1711.                 Copyright (c) 1987 Information Technology, Ltd.
  1712.  
  1713.  
  1714.  
  1715.  
  1716.  
  1717.                   LiteComm Toolbox for Datalight and Turbo C
  1718.  
  1719.  
  1720.         FUNCTION lc_peek
  1721.  
  1722.         SUMMARY
  1723.  
  1724.         #include <litecomm.h>
  1725.  
  1726.         int lc_peek(port)
  1727.  
  1728.              unsigned port;
  1729.  
  1730.  
  1731.         DESCRIPTION
  1732.  
  1733.              Look at the next character in the serial port's input buffer.
  1734.  
  1735.         RETURN VALUES
  1736.  
  1737.              Returns the next available character in the input buffer for 
  1738.              the port, but does not remove the character from the buffer. 
  1739.              This allows the application to 'look-ahead' by one character 
  1740.              in a non-destructive fashion. Returns -1 if the port is not 
  1741.              active, or if there are no characters in the port's buffer.
  1742.          
  1743.  
  1744.  
  1745.  
  1746.  
  1747.  
  1748.  
  1749.  
  1750.  
  1751.  
  1752.  
  1753.  
  1754.  
  1755.  
  1756.  
  1757.  
  1758.  
  1759.  
  1760.  
  1761.  
  1762.  
  1763.  
  1764.  
  1765.  
  1766.  
  1767.  
  1768.  
  1769.  
  1770.  
  1771.  
  1772.  
  1773.  
  1774.  
  1775.  
  1776.  
  1777.                 Copyright (c) 1987 Information Technology, Ltd.
  1778.  
  1779.  
  1780.  
  1781.  
  1782.  
  1783.                   LiteComm Toolbox for Datalight and Turbo C
  1784.  
  1785.  
  1786.         FUNCTION lc_put
  1787.  
  1788.         SUMMARY
  1789.  
  1790.         #include <litecomm.h>
  1791.  
  1792.         int lc_put(port,ch)
  1793.  
  1794.              unsigned port;
  1795.              char ch;
  1796.  
  1797.         DESCRIPTION
  1798.  
  1799.              Place a character into the serial port's output buffer.
  1800.  
  1801.         RETURN VALUES
  1802.  
  1803.              Returns 0 if successful. Note that this does not guarantee 
  1804.              that the character has been sent, only that no errors were 
  1805.              detected. Returns -1 if the port is not active, or if there 
  1806.              no room in the port's buffer.
  1807.          
  1808.  
  1809.  
  1810.  
  1811.  
  1812.  
  1813.  
  1814.  
  1815.  
  1816.  
  1817.  
  1818.  
  1819.  
  1820.  
  1821.  
  1822.  
  1823.  
  1824.  
  1825.  
  1826.  
  1827.  
  1828.  
  1829.  
  1830.  
  1831.  
  1832.  
  1833.  
  1834.  
  1835.  
  1836.  
  1837.  
  1838.  
  1839.  
  1840.  
  1841.  
  1842.  
  1843.                 Copyright (c) 1987 Information Technology, Ltd.
  1844.  
  1845.  
  1846.  
  1847.  
  1848.  
  1849.                   LiteComm Toolbox for Datalight and Turbo C
  1850.  
  1851.  
  1852.         FUNCTION lc_gets
  1853.  
  1854.         SUMMARY
  1855.  
  1856.         #include <litecomm.h>
  1857.  
  1858.         int lc_gets(port, buff, cnt)
  1859.  
  1860.              unsigned port;
  1861.              char *buff;
  1862.              int cnt;
  1863.  
  1864.         DESCRIPTION
  1865.  
  1866.              Read a stream of, at most, cnt characters from the serial 
  1867.              port's input buffer into the buff location. Not sensitive 
  1868.              to NULL character.
  1869.  
  1870.         RETURN VALUES
  1871.  
  1872.              Returns the count of characters actually transferred, or -1 
  1873.              if an error occurs. 
  1874.          
  1875.  
  1876.  
  1877.  
  1878.  
  1879.  
  1880.  
  1881.  
  1882.  
  1883.  
  1884.  
  1885.  
  1886.  
  1887.  
  1888.  
  1889.  
  1890.  
  1891.  
  1892.  
  1893.  
  1894.  
  1895.  
  1896.  
  1897.  
  1898.  
  1899.  
  1900.  
  1901.  
  1902.  
  1903.  
  1904.  
  1905.  
  1906.  
  1907.  
  1908.  
  1909.                 Copyright (c) 1987 Information Technology, Ltd.
  1910.  
  1911.  
  1912.  
  1913.  
  1914.  
  1915.                   LiteComm Toolbox for Datalight and Turbo C
  1916.  
  1917.  
  1918.         FUNCTION lc_puts
  1919.  
  1920.         SUMMARY
  1921.  
  1922.         #include <litecomm.h>
  1923.  
  1924.         int lc_puts(port, buff, cnt)
  1925.  
  1926.              unsigned port;
  1927.              char *buff;
  1928.              int cnt;
  1929.  
  1930.         DESCRIPTION
  1931.  
  1932.              Place a stream of, at most, character into the serial port's 
  1933.              output buffer.
  1934.  
  1935.         RETURN VALUES
  1936.  
  1937.              Returns the number of characters actually placed into the 
  1938.              buffer. Note that this does not guarantee that the 
  1939.              characters have been sent. Returns 0 if any error occurs, or 
  1940.              if there no room in the port's buffer.
  1941.          
  1942.  
  1943.  
  1944.  
  1945.  
  1946.  
  1947.  
  1948.  
  1949.  
  1950.  
  1951.  
  1952.  
  1953.  
  1954.  
  1955.  
  1956.  
  1957.  
  1958.  
  1959.  
  1960.  
  1961.  
  1962.  
  1963.  
  1964.  
  1965.  
  1966.  
  1967.  
  1968.  
  1969.  
  1970.  
  1971.  
  1972.  
  1973.  
  1974.  
  1975.                 Copyright (c) 1987 Information Technology, Ltd.
  1976.  
  1977.  
  1978.  
  1979.  
  1980.  
  1981.                   LiteComm Toolbox for Datalight and Turbo C
  1982.  
  1983.  
  1984.         FUNCTION lc_flush
  1985.  
  1986.         SUMMARY
  1987.  
  1988.         #include <litecomm.h>
  1989.  
  1990.         int lc_tflush(port)
  1991.  
  1992.         int lc_rflush(port)
  1993.  
  1994.         int lc_flshtrue(port, ch)
  1995.  
  1996.         int lc_nflush(port, cnt)
  1997.  
  1998.              unsigned port;
  1999.              char ch;
  2000.              int cnt;
  2001.  
  2002.         DESCRIPTION
  2003.  
  2004.              lc_tflush empties the port's tranmit buffer immediately.
  2005.  
  2006.              lc_rflush empties the port's receive buffer immediately.
  2007.  
  2008.              lc_flshtrue will continually dispose of received characters 
  2009.              until the character ch is received. Use caution with this 
  2010.              one since it does not detect port number errors.
  2011.  
  2012.              lc_nflush flushes, at most, cnt characters from the port's 
  2013.              receive buffer.
  2014.  
  2015.         RETURN VALUES
  2016.  
  2017.              lc_flshtrue returns no values. lc_tflush and lc_rflush 
  2018.              return 0 if successful and -1 if an error occurs. lc_nflush 
  2019.              returns the number of characters actually flushed from the 
  2020.              receive buffer or 0 in the case of no characters to flush, 
  2021.              or an error.
  2022.          
  2023.  
  2024.  
  2025.  
  2026.  
  2027.  
  2028.  
  2029.  
  2030.  
  2031.  
  2032.  
  2033.  
  2034.  
  2035.  
  2036.  
  2037.  
  2038.  
  2039.  
  2040.  
  2041.                 Copyright (c) 1987 Information Technology, Ltd.
  2042.  
  2043.  
  2044.  
  2045.  
  2046.  
  2047.                   LiteComm Toolbox for Datalight and Turbo C
  2048.  
  2049.  
  2050.         FUNCTION lc_sbrk
  2051.  
  2052.         SUMMARY
  2053.  
  2054.         #include <litecomm.h>
  2055.  
  2056.         int lc_sbrk(port)
  2057.  
  2058.              unsigned port;
  2059.  
  2060.         DESCRIPTION
  2061.  
  2062.              Send a break out the port;
  2063.  
  2064.         RETURN VALUES
  2065.  
  2066.              Returns 0 if successful. Returns -1 if the port is not 
  2067.              active.
  2068.          
  2069.  
  2070.  
  2071.  
  2072.  
  2073.  
  2074.  
  2075.  
  2076.  
  2077.  
  2078.  
  2079.  
  2080.  
  2081.  
  2082.  
  2083.  
  2084.  
  2085.  
  2086.  
  2087.  
  2088.  
  2089.  
  2090.  
  2091.  
  2092.  
  2093.  
  2094.  
  2095.  
  2096.  
  2097.  
  2098.  
  2099.  
  2100.  
  2101.  
  2102.  
  2103.  
  2104.  
  2105.  
  2106.  
  2107.                 Copyright (c) 1987 Information Technology, Ltd.
  2108.  
  2109.  
  2110.  
  2111.  
  2112.  
  2113.                   LiteComm Toolbox for Datalight and Turbo C
  2114.  
  2115.  
  2116.                               HAYES MODEM FUNCTIONS
  2117.  
  2118.         Note - When using the following functions, you must include the 
  2119.         file litehcm.h in your program. litehcm.h automatically includes 
  2120.         the litecomm.h header file.
  2121.  
  2122.         FUNCTIONS lch_codeset
  2123.                     lch_dial
  2124.                     lch_fduplex
  2125.                     lch_hduplex
  2126.                     lch_greg
  2127.                     lch_sreg
  2128.                     lch_offcarr
  2129.                     lch_oncarr
  2130.                     lch_offecho
  2131.                     lch_onecho
  2132.                     lch_hook
  2133.                     lch_redo
  2134.                     lch_numres
  2135.                     lch_wrdres
  2136.                     lch_codesoff
  2137.                     lch_codeson
  2138.                     lch_pulse
  2139.                     lch_tone
  2140.                     lch_speaker
  2141.                     _retset
  2142.                     _rettype
  2143.  
  2144.         SUMMARY
  2145.  
  2146.         #include <litehcm.h>
  2147.  
  2148.         int lch_codeset(port,mode)
  2149.  
  2150.         int lch_dial(port,dstr)
  2151.  
  2152.         int lch_fduplex(port)
  2153.  
  2154.         int lch_hduplex(port)
  2155.  
  2156.         int lch_greg(port,reg)
  2157.  
  2158.         int lch_sreg(port,reg,value)
  2159.  
  2160.         int lch_offcarr(port)
  2161.  
  2162.         int lch_oncarr(port)
  2163.  
  2164.         int lch_offecho(port)
  2165.  
  2166.         int lch_onecho(port)
  2167.  
  2168.         int lch_hook(port,hmode)
  2169.  
  2170.         int lch_redo(port)
  2171.  
  2172.  
  2173.                 Copyright (c) 1987 Information Technology, Ltd.
  2174.  
  2175.  
  2176.  
  2177.  
  2178.  
  2179.                   LiteComm Toolbox for Datalight and Turbo C
  2180.  
  2181.  
  2182.         SUMMARY (ctd.)
  2183.  
  2184.         int lch_numres(port)
  2185.  
  2186.         int lch_wrdres(port)
  2187.  
  2188.  
  2189.         int lch_codesoff(port)
  2190.  
  2191.         int lch_codeson(port)
  2192.  
  2193.         int lch_pulse(port)
  2194.  
  2195.         int lch_tone(port)
  2196.  
  2197.         int lch_speaker(port,spkmode)
  2198.  
  2199.         int _retset()
  2200.  
  2201.         int _rettype()
  2202.  
  2203.              unsigned port;
  2204.              unsigned mode;
  2205.              char *dstr;
  2206.              unsigned reg;
  2207.              int value;
  2208.              unsigned hmode;
  2209.              unsigned spkmode; 
  2210.  
  2211.         DESCRIPTION
  2212.              
  2213.              The values to be used in conjunction with mode, hmode, and 
  2214.              spkmode are defined in the #include-d file litehcm.h.
  2215.  
  2216.              The lch_codeset function allows you to change the set of 
  2217.              codes that are returned by the modem when an action is 
  2218.              specified.
  2219.  
  2220.              lch_dial instructs the modem to dial the number contained in 
  2221.              dstr. Do not include the dialing (ATD) prefix, or the 
  2222.              trailing <CR>. These are provided by the function. You may 
  2223.              include non-numeric characters as the contents of dstr are 
  2224.              not checked. The dialing is done in the last known, pulse or 
  2225.              tone, mode. If you use the lch_pulse or lch_tone functions, 
  2226.              then dialing will be done in the mode that was last 
  2227.              correctly enabled. If you have not exercised these 
  2228.              functions, then dialing occurs in the modems default or 
  2229.              power-up mode.
  2230.  
  2231.              The lch_hduplex and lch_fduplex functions place the modem 
  2232.              into local echo and remote echo modes respectively.
  2233.  
  2234.              The lch_greg function requests that the modem report the 
  2235.              current value of S-register reg. Reg must be in the range 0 
  2236.              to 13. Use the lch_gets, or similar function, to retrieve 
  2237.  
  2238.  
  2239.                 Copyright (c) 1987 Information Technology, Ltd.
  2240.  
  2241.  
  2242.  
  2243.  
  2244.  
  2245.                   LiteComm Toolbox for Datalight and Turbo C
  2246.  
  2247.  
  2248.              the modem's response. Specifying a register outside the 0 
  2249.              to 13 range will cause a return of -1.
  2250.  
  2251.              lch_sreg is the companion to lch_greg, with the same 
  2252.              restrictions. Sets the S-register reg to the value 
  2253.              contained in value. If value contains -1, then the register 
  2254.              is reset to its default (power-up) value. The function 
  2255.              checks the value to be certain that it is within the limits 
  2256.              specified for the particular register, and returns a value 
  2257.              of -1 if the value is outside the predefined limits.
  2258.  
  2259.              lch_offcarr enables modem carrier detect, but disables the 
  2260.              modems carrier signal. The lch_oncarr companion enables 
  2261.              both carrier detect and the modems carrier signal. When 
  2262.              lch_offcarr is used the modem will receive data but will be 
  2263.              unable to send data.
  2264.  
  2265.              The lch_offecho and lch_onecho functions determine whether 
  2266.              commands sent to the modem are echoed back to the sending 
  2267.              program. With echo turned off, the modem will continue to 
  2268.              accept commands, but will not try to redisplay the command's 
  2269.              characters.
  2270.  
  2271.              lch_hook allows you to control the current status of the 
  2272.              modem's telephone line connection. See your modem's 
  2273.              documentation and the include file for additional 
  2274.              information.
  2275.  
  2276.              The lch_redo function instructs the modem to repeat the last 
  2277.              command sequence executed. Generally, this function is of 
  2278.              greatest value in re-dialing numbers that are busy, although 
  2279.              its use is not restricted to that.
  2280.  
  2281.              The way in which your modem responds to commands is 
  2282.              determined, in part by the lch_wrdres and lch_numres 
  2283.              functions. If you call lch_wrdres, then modem responses use 
  2284.              the english language response codes, e.g. CONNECT or OK. 
  2285.              Calling lch_numres instructs the modem to respond with code 
  2286.              numbers only from the currently selected response set, see 
  2287.              the lch_codeset function above.
  2288.  
  2289.              You may use the functions lch_codeson and lch_codesoff to 
  2290.              specify whether you want your modem to send back response 
  2291.              codes when it receives a command string. In a sense, these 
  2292.              act as companions to the lch_xxxecho functions above.
  2293.  
  2294.              Use the lch_speaker function to control the modem's internal 
  2295.              speaker, if it has one. See litehcm.h for the applicable 
  2296.              codes.
  2297.  
  2298.              The _retset and _rettype functions return, respectively, the 
  2299.              last known command set (lch_codeset) and last known result 
  2300.              type (lch_wrdres, lch_numres). These functions (_retset, 
  2301.              _rettype) are only of value when used in conjunction with 
  2302.              the companion functions.
  2303.  
  2304.  
  2305.                 Copyright (c) 1987 Information Technology, Ltd.
  2306.  
  2307.  
  2308.  
  2309.  
  2310.  
  2311.                   LiteComm Toolbox for Datalight and Turbo C
  2312.  
  2313.  
  2314.         GENERAL REMARKS
  2315.  
  2316.              Several considerations are in order if you intend to use the 
  2317.              Hayes ToolBox functions.
  2318.  
  2319.              You are responsible for checking the return codes from the 
  2320.              modem once you have given modem a command. To make the task 
  2321.              easier, we suggest that you turn OFF command echo (so that 
  2322.              you don't have to worry about separating commands from 
  2323.              responses) and turn ON numeric responses (to make the 
  2324.              interpretation of result codes easier and faster).
  2325.  
  2326.              One final caution is in order. Be sure that you allow 
  2327.              adequate time between commands for the modem to process the 
  2328.              command and respond. Failure to observe this rule may 
  2329.              result in commands being misinterpreted or "lost". You can 
  2330.              monitor the number of characters in the receive buffer to 
  2331.              help you with the timing. Or alternatively, check the 
  2332.              reponse after each command. The latter approach is more in 
  2333.              line with what we believe to be good programming practice. 
  2334.  
  2335.         RETURN VALUES
  2336.  
  2337.              All functions return a value of -1 if a port or other error 
  2338.              is detected, zero otherwise.
  2339.  
  2340.  
  2341.  
  2342.  
  2343.  
  2344.  
  2345.  
  2346.  
  2347.  
  2348.  
  2349.  
  2350.  
  2351.  
  2352.  
  2353.  
  2354.  
  2355.  
  2356.  
  2357.  
  2358.  
  2359.  
  2360.  
  2361.  
  2362.  
  2363.  
  2364.  
  2365.  
  2366.  
  2367.  
  2368.  
  2369.  
  2370.  
  2371.                 Copyright (c) 1987 Information Technology, Ltd.
  2372.  
  2373.  
  2374.  
  2375.  
  2376.  
  2377.                   LiteComm Toolbox for Datalight and Turbo C
  2378.  
  2379.  
  2380.                              MISCELLANEOUS FUNCTIONS
  2381.  
  2382.         These additional functions, while part of the LiteComm library, 
  2383.         are intended for use with LXM, the xmodem engine.
  2384.  
  2385.         FUNCTION lc_insclock
  2386.  
  2387.         SUMMARY
  2388.  
  2389.         #include <lctime.h>
  2390.  
  2391.         int lc_insclock() /* install programmable timer */
  2392.  
  2393.         void lc_clrclock() /* remove programmable timer */
  2394.  
  2395.         DESCRIPTION
  2396.  
  2397.              Install the programmable interval timer at interrupt vector 
  2398.              0X1C, if not alreay installed. You must use this function 
  2399.              before attempting to access any of the other functions in 
  2400.              this set. In addition, Datalight users must, upon 
  2401.              termination of their program, reset the vector by using the 
  2402.              lc_clrclock function. Turbo C users need to know that the 
  2403.              atexit() function is used in the Turbo C version to 
  2404.              automatically replace the vector by calling lc_clrclock.
  2405.  
  2406.         RETURN VALUES
  2407.  
  2408.              Lc_insclock always returns 0, lc_clrclock never returns a 
  2409.              value.
  2410.          
  2411.  
  2412.  
  2413.  
  2414.  
  2415.  
  2416.  
  2417.  
  2418.  
  2419.  
  2420.  
  2421.  
  2422.  
  2423.  
  2424.  
  2425.  
  2426.  
  2427.  
  2428.  
  2429.  
  2430.  
  2431.  
  2432.  
  2433.  
  2434.  
  2435.  
  2436.  
  2437.                 Copyright (c) 1987 Information Technology, Ltd.
  2438.  
  2439.  
  2440.  
  2441.  
  2442.  
  2443.                   LiteComm Toolbox for Datalight and Turbo C
  2444.  
  2445.  
  2446.         FUNCTION lc_setclock
  2447.  
  2448.         SUMMARY
  2449.  
  2450.         #include <lctime.h>
  2451.  
  2452.         void lc_setclock(secs)
  2453.  
  2454.           unsigned secs;
  2455.  
  2456.  
  2457.         DESCRIPTION
  2458.  
  2459.              Sets the programmable timer to the number of seconds 
  2460.              specified in secs. The amount of time remaining on the 
  2461.              clock, in seconds, can be examined in the _secs_rem 
  2462.              variable, defined in lctime.h. _secs_rem will never 
  2463.              decrease below a value of zero.
  2464.  
  2465.         RETURN VALUES
  2466.  
  2467.              Lc_setclock never returns a value. 
  2468.  
  2469.  
  2470.  
  2471.  
  2472.  
  2473.  
  2474.  
  2475.  
  2476.  
  2477.  
  2478.  
  2479.  
  2480.  
  2481.  
  2482.  
  2483.  
  2484.  
  2485.  
  2486.  
  2487.  
  2488.  
  2489.  
  2490.  
  2491.  
  2492.  
  2493.  
  2494.  
  2495.  
  2496.  
  2497.  
  2498.  
  2499.  
  2500.  
  2501.  
  2502.  
  2503.                 Copyright (c) 1987 Information Technology, Ltd.
  2504.  
  2505.  
  2506.  
  2507.  
  2508.  
  2509.  
  2510.  
  2511.  
  2512.                                 REGISTRATION FORM
  2513.  
  2514.         Please complete the following information. Note that the prices 
  2515.         below are for a single-use registration only. Please contact us 
  2516.         directly for site licensing.
  2517.  
  2518.              Mail to:
  2519.                   Information Technology
  2520.                   PO Box 554
  2521.                   Coventry, RI 02816
  2522.                   (401) 826-2223
  2523.          
  2524.                   Name: _____________________________________
  2525.  
  2526.                   Company: __________________________________
  2527.  
  2528.                   Street Addr: ______________________________
  2529.  
  2530.                                ______________________________
  2531.  
  2532.                  City: ______________________ State: ____
  2533.  
  2534.                  Zip Code: _________________
  2535.  
  2536.                  Telephone: _______________________
  2537.  
  2538.  
  2539.             Indicate the type and number of registrations below. All
  2540.             prices include postage and handling.
  2541.  
  2542.             Number Type Registration Amount
  2543.  
  2544.             _____ Libraries ONLY - $25 ______________
  2545.  
  2546.             _____ Libraries and Source Code ______________
  2547.                           $50
  2548.  
  2549.             Method of Payment (Check, Mastercard, Visa) _____________
  2550.  
  2551.             MasterCard/Visa Number __________________________
  2552.  
  2553.             Expiration Date __________________________
  2554.  
  2555.             Name as it appears on card ______________________________
  2556.  
  2557.             Signature for MC/VISA ___________________________________
  2558.  
  2559.             All MasterCard/Visa orders must include a telephone number,
  2560.  
  2561.             We regret that we cannot accept COD orders
  2562.         -----------------------------------------------------------------
  2563.         (office use only)
  2564.             Date Received ______________
  2565.             Date Sent ______________
  2566.             Version ______________ Serial Number _______________
  2567.  
  2568.  
  2569.                                        39
  2570.  
  2571.  
  2572.  
  2573.  
  2574.  
  2575.  
  2576.  
  2577.  
  2578.                     
  2579.  
  2580.  
  2581.  
  2582.  
  2583.  
  2584.  
  2585.  
  2586.  
  2587.  
  2588.  
  2589.  
  2590.  
  2591.  
  2592.  
  2593.  
  2594.  
  2595.  
  2596.  
  2597.  
  2598.  
  2599.  
  2600.  
  2601.  
  2602.  
  2603.  
  2604.  
  2605.  
  2606.  
  2607.  
  2608.  
  2609.  
  2610.  
  2611.  
  2612.  
  2613.  
  2614.  
  2615.  
  2616.  
  2617.  
  2618.  
  2619.  
  2620.  
  2621.  
  2622.  
  2623.  
  2624.  
  2625.  
  2626.  
  2627.  
  2628.  
  2629.  
  2630.  
  2631.  
  2632.  
  2633.  
  2634.  
  2635.                                        40
  2636.  
  2637.  
  2638.  
  2639.  
  2640.  
  2641.